#lang scribble/doc

@(require scribble/manual)
@(require "../constructors/constructor-defer.rkt")

@title{Rosetta}
@declare-exporting[Rosetta]

@section{Defer constructors}

Defer constructors are functions that produce geometric shapes in a lazy fashion.
This means that in fact these constructors return a node instead of an actual shape,
which when evaluated will produce the desired shape. The shapes are evaluated by the
function 'evaluate' or 'evaluate-toplevel'. However, the user does not have to worry
about this evaluation model because it happens automatically in most cases.


@subsection{Lines}

@defproc[(arc (angle angle?) (radius distance?)) shape?]{
Creates a circular arc centered at the origin of angle @racket[angle] (radians)
with the X-axis and radius @racket[radius].
}

@defproc[(elliptical-arc
          (angle angle?)
          (x-radius distance?)
          (y-radius distance?))
         shape?]{
Creates an elliptical arc centered at the origin of angle @racket[angle] (radians)
with the X-axis and radius @racket[x-radius] along the X-axis and radius
@racket[y-radius] along the Y-axis.
}

@defproc[(circle
          (radius distance?))
         shape?]{
Creates a circular line centered at the origin of radius @racket[radius].
}

@defproc[(ellipse
          (x-radius distance?)
          (y-radius distance?))
         shape?]{
Creates an elliptical line centered at the origin of radius @racket[x-radius] along
the X-axis and radius @racket[y-radius] along the Y-axis.
}

@defproc[(helix-2d
          (base-radius distance?)
          (top-radius distance?)
          (turns (and/c integer? positive?))
          (turn-height distance?)
          (direction (or 'cw 'ccw)))
         shape?]{TODO}

@defproc[(line
          (points (listof point?)))
         shape?]{
Creates a line composed of straight line segments passing through the
points specified by @racket[points]. If the last point is equal to the
first point then the line is closed; otherwise the line is closed.
}

@defproc[(line (point1 point?) (point2 point?) ...) shape?]{
A convenience function for the previous 'line' constructor.
}

@defproc[(line-closed (points (listof point?))) shape?]{
Creates a closed line composed of straight line segments passing
through the points in @racket[points]. The first point and the last
must not be equal.
}

@defproc[(line-closed (point1 point?) (point2 point?) ...) shape?]{
A convenience function for the previous 'line-closed' constructor.
}

@defproc[(ngon (width distance?) (sides (and/c integer? positive?))) shape?]{TODO}

@defproc[(nurbs-curve
          (controls (listof point?))
          (knots (listof (and/c integer? (not/c negative?)))))
         shape?]{
Creates a Non-Uniform Rational B-Spline (NURBS) curve where @racket[controls] is a
list of control points and @racket[knots] is the list of knots.
}

@defproc[(nurbs-surface
          (controls (listof point?))
          (u-knots (listof (and/c integer? (not/c negative?))))
          (v-knots (listof (and/c integer? (not/c negative?)))))
         shape?]{
Creates a Non-Uniform Rational B-Spline (NURBS) surface where @racket[controls] is the
list of control points, @racket[u-knots] is the list of knots in the U-direction
and @racket[v-knots] is the list of knots in the V-direction.
}

@defproc[(spline (points (listof point?))) shape?]{
Creates a spline that interpolates the points specified by @racket[points].
}

@defproc[(spline (p1 point?) (p2 point?) ...) shape?]{
A convenience function for the previous 'spline' constructor.
}

@defproc[(star (width distance?) (sides (and/c integer? positive?)) (stride (and/c integer? positive?))) shape?]{TODO}


@subsection{Surfaces}

@defproc[(circle-surface (radius distance?)) shape?]{
Creates a circular surface in the XY-plane, centered at the origin, of
radius @racket[radius].
}

@defproc[(donut (inner-radius distance?) (outer-radius distance?)) shape?]{
Creates a donut surface in the XY-plane, centered at the origin, of
inner radius @racket[inner-radius] and outer radius
@racket[outer-radius]. A donut surface is the surface that results
from subtracting two concentrical circular surfaces of different
radii.
}

@defproc[(rectangle (width distance?) (length distance?)) shape?]{
Creates a rectangular surface in the XY-plane, centered at the origin,
and aligned with the coordinate system, of size @racket[width] along
the X-axis and @racket[length] along the Y-axis.
}

@defproc[(surface (p1 point?) (p2 point?) (p3 point?)) shape?]{
Creates a surface where @racket[p1], @racket[p2] and @racket[p3]
define the corners of the surface.
}

@defproc[(surface (p1 point?) (p2 point?) (p3 point?) (p4 point?)) shape?]{
Creates a surface where @racket[p1], @racket[p2], @racket[p3] and
@racket[p4] define the corners of the surface.
}

 
@subsection{Solids}

@defproc[(box (width distance?) (length distance?) (height distance?)) shape?]{
Creates a solid parallelepiped, centered at the origin, and aligned
with the coordinate system, of size @racket[width] along the X-axis,
@racket[length] along the Y-axis and @racket[height] along the Z-axis.
}
                
@defproc[(cone (radius distance?) (height distance?)) shape?]{
Creates a solid cone, oriented along the Z-axis, with base centered at
the origin, in the XY-plane, of radius @racket[radius], and of height
@racket[height].
}
                
@defproc[(cone-frustrum (base-radius distance?) (top-radius distance?) (height distance?)) shape?]{
Creates a solid truncated cone, oriented along the Z-axis, with bottom
base centered at the origin, in the XY-plane, of radius
@racket[base-radius], with top base perpendicular to the Z-axis and of
radius @racket[top-radius], and of height @racket[height].
}

@defproc[(cylinder (radius distance?) (height distance?)) shape?]{
Creates a solid cylinder, oriented along the Z-axis, with bottom base
centered at the origin, in the XY-plane, of radius @racket[radius],
with top base perpendicular to the Z-axis, and of height
@racket[height].
}

@defproc[(pipe (inner-radius distance?) (outer-radius distance?) (height distance?)) shape?]{
Creates a solid pipe, oriented along the Z-axis, with bottom base
centered at the origin, in the XY-plane, of inner radius
@racket[inner-radius] and outer radius @racket[outer-radius], with top
base perpendicular to the Z-axis, and of height @racket[height]. A
pipe is a solid that results from subtracting two concentrical
cylinders of different radii.
}

@defproc[(sphere (radius distance?)) shape?]{
Creates a solid sphere, centered at the origin, of radius
@racket[radius].
}
                
 
@subsection{Operations}

@defproc[(extrude ...) shape?]{TODO}

@defproc[(intersect (shapes (listof shape?))) shape?]{
Creates a shape that results from intersecting the shapes specified by
@racket[shapes].
}

@defproc[(intersect (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous 'intersect' constructor.
}

@defproc[(join ...) shape?]{TODO}
@defproc[(loft-closed ...) shape?]{TODO}

@defproc[(move (position point?) (shape shape?)) shape?]{
Creates a shape that results from translating the shape specified by
@racket[shape].
}

@defproc[(offset ...) shape?]{TODO}

@defproc[(rotate (angle angle?) (normal point?) (shape shape?)) shape?]{
Creates a shape that results from rotation the shape specified by
@racket[shape], where @racket[angle] is the rotation angle in radians
and @racket[normal] is the normal vector that defines the rotation.
}

@defproc[(scale (size point?) (shape shape?)) shape?]{
Creates a shape that results from scaling the shape specified by
@racket[shape], where @racket[size] is the vector that contains the
scaling factor for the X, Y and Z components. Negative scaling factors
will produce mirrored shapes.
}

@defproc[(subtract (shape shape?) (shapes (listof shape?))) shape?]{
Creates a shape that results from subtracting @racket[shape] to
@racket[shapes].
}

@defproc[(subtract (shapes (listof shape?))) shape?]{
A convenience function for the previous 'subtract' constructor, where
the first shape in @racket[shapes] will be subtracted the remaining
shapes in @racket[shapes].
}

@defproc[(subtract (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous 'subtract' constructor.
}
 
@defproc[(sweep (shape shape?) (path shape?)) shape?]{
Creates a shape that results from sweeping @racket[shape] along
@racket[path].
}

@defproc[(union (shapes (listof shape?))) shape?]{
Creates a shape that results from uniting the shapes specified by
@racket[shapes].
}

@defproc[(union (shape1 shape?) (shape2 shape?)) shape?]{
A convenience function for the previous 'union' constructor.
}


@subsection{Linguistic primitives}

@defproc[(align ...) shape?]{TODO}

@defproc[(on (type symbol?) (listof shapes)) shape?]{
Creates a shape for each shape in @racket[shapes] such that the
bounding boxes of the resulting shapes are aligned according to the
criteria specified by @racket[type]. The possible values of
@racket[type] are @racket['+x], @racket['-x], @racket['+y],
@racket['-y], @racket['+z], @racket['-z], @racket['right],
@racket['left], @racket['back], @racket['front], @racket['top] and
@racket['bottom]. For example, type value @racket['top], which is a
synonym for @racket['+z], applied to shapes A and B will cause shape A
to be ontop of shape B.
}

@defproc[(on (type symbol?) (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous 'on' constructor.
}

@defproc[(on-right (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['right].
}

@defproc[(on-right (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

@defproc[(on-left (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['left].
}

@defproc[(on-left (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

@defproc[(on-back (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['back].
}

@defproc[(on-back (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

@defproc[(on-front (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['front].
}

@defproc[(on-front (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

@defproc[(on-top (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['top].
}

@defproc[(on-top (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

@defproc[(on-bottom (listof shapes)) shape?]{
A convenience function for the 'on' constructor with type of value
@racket['bottom].
}

@defproc[(on-bottom (shape1 shape?) (shape2 shape?) ...) shape?]{
A convenience function for the previous constructor.
}

 
@section{Imediate Constructors}

Imediate constructors are functions that, contrary to defer constructors,
are imediately evaluated. Therefore, they act just like normal functions.


@subsection{Evaluation}

@defproc[(evaluate (exp any/c)) any/c]{
If @racket[exp] refers to a shape created by a defer constructor and there
is a backend selected then @racket[exp] is evaluated within the selected
backend and the resulting shape is returned. Otherwise, @racket[exp] itself
is returned. This function should only be directly invoked in special cases.
}

@defproc[(evaluate-toplevel (exp any/c)) any/c]{
Same as @racket[evaluate] however it allows for optimizations to take place
because this function is intended to be invoked at the toplevel. This function
should only be directly invoked in special cases.
}
 
 
@subsection{Linguistic primitives}

@defproc[(bounding-box (shape shape?)) bbox?]{TODO}
@defproc[(par (shape shape?)) parametric?]{TODO}
 
@subsection{Properties}

@defproc[(curve-begin-point ...) shape?]{TODO}
@defproc[(curve-end-point ...) shape?]{TODO}

@subsection{CAD specific}

@defproc[(begin-undo-mark ...) shape?]{TODO}
@defproc[(end-undo-mark ...) shape?]{TODO}
@defproc[(undo) void?]{TODO}
 
 
@section{High-level constructors}
 
@defproc[(arc-cs ...) shape?]{TODO}
@defproc[(box-center ...) shape?]{TODO}
@defproc[(box-n ...) shape?]{TODO}
@defproc[(box-p ...) shape?]{TODO}
@defproc[(box-pp ...) shape?]{TODO}
@defproc[(circle-p ...) shape?]{TODO}
@defproc[(circle-n ...) shape?]{TODO}
@defproc[(circle-p-n ...) shape?]{TODO}
@defproc[(cone-pp ...) shape?]{TODO}
@defproc[(cone-frustrum-pp ...) shape?]{TODO}
@defproc[(cylinder-pp ...) shape?]{TODO}
@defproc[(rotate-pp ...) shape?]{TODO}
@defproc[(sphere-p ...) shape?]{TODO}